What

• Add pkg/dcgm/doc.go with a comprehensive package-level documentation comment
• Fix a stray package comment in diag.go (mid-file, not at the package declaration) that confused godoc parsers
• Remove the now-duplicate package comment from hostengine_status.go
• Expand godoc for WatchFieldsWithGroupEx to document all three parameters and their units
• Expand godoc for WatchFieldsWithGroup with default parameter values and a complete runnable example

Why

The package currently has no doc.go and the only package-level comment is a single line spread across two files (diag.go and hostengine_status.go). There are no usage examples in the package documentation, which makes it difficult for new users to:

• Discover the correct initialisation sequence (Init modes)
• Understand the relationship between field groups, GPU groups, and watches
• Know which cleanup functions to call (and when) to avoid resource leaks
• Find the health-check, policy-violation, and diagnostics APIs

Without this documentation the entry point for learning the package is the samples/ directory, which is not linked from pkg/go.dev and requires reading multiple source files.

How

New pkg/dcgm/doc.go covers:

• Package overview and DCGM background
• All three Init modes (Embedded, Standalone, StartHostengine) with examples
• Complete field-watch workflow (FieldGroupCreate → WatchFieldsWithGroup → GetValuesSince → cleanup)
• GPU group management (GroupAllGPUs, CreateGroup, AddToGroup, DestroyGroup)
• Health check setup and result inspection
• Policy violation monitoring with context cancellation
• Diagnostics (RunDiag)
• Thread-safety guarantees
• Resource management patterns and the consequences of leaking handles

diag.go: Remove the // Package dcgm ... line at line 14 (inside the file body, after the import block). Go's godoc tool ignores package comments that are not immediately above the package keyword, but having them in the middle of a file is confusing and was creating noise in editors.

hostengine_status.go: Remove the duplicate // Package dcgm ... comment now that doc.go is the canonical package doc location. Go uses the first package comment it finds; multiple comments in different files produce unpredictable output.

fields.go:

• WatchFieldsWithGroupEx: add parameter descriptions with units (microseconds for updateFreq, seconds for maxKeepAge)
• WatchFieldsWithGroup: add the concrete default values (30 s, unlimited age, 1 sample) and a copy-paste-ready example

Testing

• go vet ./... passes (requires CGo toolchain; the package comment changes have no runtime effect)
• go doc ./pkg/dcgm now renders the full package overview
• Verified no duplicate package comments remain with grep -rn "Package dcgm" pkg/dcgm/

Checklist

• Documentation only — no logic changes, no API changes
• All examples in doc.go follow patterns already established in samples/
• go build compatible (doc.go contains only a package comment and the package dcgm declaration)
• No new dependencies